Skip to content

docs(skills): improve drafting skills from signal log patterns 2026-08-03 - #454

Open
oz-by-warp[bot] wants to merge 6 commits into
mainfrom
docs/improve-drafting-skills-2026-08-03
Open

docs(skills): improve drafting skills from signal log patterns 2026-08-03#454
oz-by-warp[bot] wants to merge 6 commits into
mainfrom
docs/improve-drafting-skills-2026-08-03

Conversation

@oz-by-warp

@oz-by-warp oz-by-warp Bot commented Aug 3, 2026 •
edited by rachaelrenk
Loading

Copy link
Copy Markdown
Contributor

Patterns addressed

  1. ui_label_accuracy / source verification (human feedback across 14+ clean PRs, including 399, 401, 402, 404, 405)
    • Reviewers repeatedly corrected invented or stale CLI flags, permission defaults, and UI chrome that did not match warp-internal / shipped product behavior.
  2. Durable vs ephemeral UI detail (human feedback across multiple PRs, especially 399 and 404)
    • Humans trimmed glyph-color inventories, layout narration, and other presentation detail that drifts; agents should document durable workflows and shortcuts instead.
  3. Availability / platform honesty (human feedback on content_structure and feature_status_accuracy, e.g. 373, 374)
    • Preview-only, platform-limited, or interactive-only behavior was sometimes written as generally available.
  4. Team-wide / admin effects for integrations (human feedback on missing_context, e.g. 281, 338)
    • Integration drafts often omitted who can install, whether teammates get access immediately, and per-user auth steps.
  5. Related pages dead-ends (human feedback on link_quality, e.g. 281, 295, 407)
    • New feature/integration pages shipped without sibling or next-step cross-links.

Signal window: last 30 days (2026-07-04 → 2026-08-03).
Primary source: GitHub human review comments and verdicts on agent-coauthored merged PRs (noise from Oz /oz-review template verdicts filtered out).
Oz [SIGNAL:style-lint] / [SIGNAL:pr-review] markers: 0 found in drafting-related run conversations (inner loop still not emitting markers reliably).
Standing signal-log PR: #433

Improvement targets

  • .agents/skills/draft_docs/SKILL.md — require source/live verification for labels/flags/defaults; add durable-UI, availability, team-access, and Related pages rules plus checklist items (applies to all drafting skills that route through draft_docs).
  • .agents/templates/feature-doc.md — bracket instructions for platform/preview limits, source-verified procedures, integration admin/access prerequisites, and required Related pages.
  • .agents/templates/guide-page.md — required VideoEmbed title, team-tool access prerequisites, and durable prompt/UI guidance.

Patterns reviewed but not acted on

  • callout / settings_path / content_structure (chronology, Troubleshooting placement) — already proposed in open PR docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450; not duplicated here.
  • list_format / heading_specificity / terminology / scannability — already covered by existing step 6.5 rules and glossary guidance; remaining hits were page-specific accuracy.
  • frontmatter {{TOKEN}} substitution bugs — appears to be a build/transform issue called out in human replies (tokens not substituted), not a missing drafting-skill example; needs eng follow-up rather than another skill bullet.
  • general — heterogeneous product-accuracy feedback; no single skill edit would prevent it.
  • missing_media — mixed human preference (add screenshot vs land without media); PR 450 already tightens screenshot discipline.

Open questions for human review

  1. Should source verification be a hard blocker (omit unverified claims) even when only a PRD is available and warp-internal is not checked out? Resolved: not a hard blocker. The agent may omit the claim or keep it with an inline {/* VERIFY: ... */} marker, but reporting is now mandatory — draft_docs step 9.5 requires every unverified claim to be listed in an ## Unverified claims section of the PR description (or in the response for local sessions), and create_pr requires that section even when the list is empty.
  2. Is “Related pages required on every new feature/integration page” too strict for thin stub pages that will grow later?
  3. Inner-loop SIGNAL emission is still 0/30 days — worth a dedicated fix so style_lint/pr-review counts feed this loop automatically?
  4. Open PR docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450 overlaps thematically (callouts/orientation/structure); consider merging docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450 first, then this PR, or combining after review.

Test plan

  • git diff --check clean
  • YAML frontmatter parse check on changed skill/template files
  • Human review of whether the new rules match intended style guide emphasis

Conversation: https://app.warp.dev/conversation/23ca1da7-5292-48dc-bb3d-bb8a337eb730
Run: https://app.warp.dev/conversation/23ca1da7-5292-48dc-bb3d-bb8a337eb730
This PR was generated with Oz.

@vercel

vercel Bot commented Aug 3, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs Ready Ready Preview Aug 4, 2026 4:51pm

Request Review

@cla-bot cla-bot Bot added the cla-signed label Aug 3, 2026
@hongyi-chen
hongyi-chen requested a review from rachaelrenk August 3, 2026 17:50
@hongyi-chen
hongyi-chen marked this pull request as ready for review August 3, 2026 17:50
@oz-for-oss

oz-for-oss Bot commented Aug 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss[bot]
oz-for-oss Bot reviewed Aug 3, 2026
View reviewed changes

@oz-for-oss oz-for-oss Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overview

This PR updates the docs drafting skill and feature/guide templates to require source or live-product verification for user-facing labels and flags, prefer durable behavior over ephemeral UI details, state availability limits, cover team/admin effects for integrations, and strengthen related-page expectations.

Concerns

  • No blocking concerns found in the attached diff. The supplemental security pass found no changed code or configuration introducing security-relevant risk, and spec_context.md reports that no approved or repository spec context exists for spec-drift review.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

@oz-agent
docs: fix stale Docs Agent environment reference in weekly-404-monito…
d837a53 
…r skill

Co-Authored-By: Oz <oz-agent@warp.dev>
@rachaelrenk rachaelrenk mentioned this pull request Aug 3, 2026
Closed
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread .agents/skills/draft_docs/SKILL.md
- **Document durable behavior, not ephemeral chrome** — Prefer workflows, shortcuts, and outcomes that stay true when styling shifts. Drop glyph colors, pixel-level layout narration, and other pure presentation detail unless the reader must recognize them to succeed. ✅ "Press `Ctrl+C` once to stop the in-progress response." ❌ a full inventory of pending/running/failed glyph colors
- **State availability honestly** — If a capability is preview-only, platform-limited, interactive-only, or not yet in cloud agents, say so next to the claim. Never describe limited-preview behavior as generally available. ✅ "Linux post-processing adds smart cut; macOS applies a uniform speedup." ❌ listing smart cut as a property of every recording
- **Cover team-wide and admin effects** — For integrations and team features, state who can install, whether every teammate gets access immediately, and any per-user auth or admin steps on the external system. ✅ "A Jira admin must install the app; each teammate links their own account for run attribution." ❌ setup steps that only describe the installer's happy path
- **Related pages are required on new pages** — End new feature, integration, and guide pages with a Related pages (or Next steps) section. Link siblings and the natural next workflow so the page does not dead-end. ✅ Integrations overview + Agent Management Panel + a sibling Slack/Linear page ❌ no cross-links after Troubleshooting

@rachaelrenk rachaelrenk Aug 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This rule may be too strict for thin and newer stub pages that will be expanded on later. Update rule to include some flexibility around this. If there a logical and valuable next step exists, we should include that on the docs page.

@rachaelrenk @warp-agent
docs(skills): require unverified claims to be reported, not just marked
f6319bf 
Resolves the open question on source verification: keep the escape hatch
for drafts written without warp-internal/warp-server access, but make it
non-skippable. Unverified UI labels, flags, defaults, and eligibility
claims must be marked inline and surfaced in an Unverified claims section
of the PR description (or in the response for local sessions).

Co-Authored-By: Warp Agent <agent@warp.dev>
@oz-by-warp oz-by-warp Bot mentioned this pull request Aug 4, 2026
Draft
4 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rachaelrenk rachaelrenk rachaelrenk left review comments
@oz-for-oss oz-for-oss[bot] oz-for-oss[bot] left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

cla-signed

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@rachaelrenk @oz-agent @hongyi-chen